Celestin Apprentice 7

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 7 / Apprentice-Release7.iso / Environments / PowerLisp 2.01 / Supplemental Documentation / Documentation / Chapter 25. Misc. Features < prev next >

Wrap

Text File | 1995-03-27 | 63.2 KB | 1,364 lines | [TEXT/ROSA]

Common Lisp the Language, 2nd Edition ------------------------------------------------------------------------------- 25. Miscellaneous Features In this chapter are described various things that don't seem to fit neatly anywhere else in this book: the compiler, the documentation function, debugging aids, environment inquiries (including facilities for calculating and measuring time), and the identity function. ------------------------------------------------------------------------------- * The Compiler o Compiler Diagnostics o Compiled Functions o Compilation Environment o Similarity of Constants * Documentation * Debugging Tools * Environment Inquiries o Time Functions o Other Environment Inquiries * Identity Function ------------------------------------------------------------------------------- 25.1. The Compiler [old_change_begin] The compiler is a program that may make code run faster by translating programs into an implementation-dependent form that can be executed more efficiently by the computer. Most of the time you can write programs without worrying about the compiler; compiling a file of code should produce an equivalent but more efficient program. When doing more esoteric things, you may need to think carefully about what happens at ``compile time'' and what happens at ``load time.'' Then the difference between the syntaxes #. and #, becomes important, and the eval-when construct becomes particularly useful. [old_change_end] [change_begin] X3J13 voted in January 1989 (SHARP-COMMA-CONFUSION) to remove #, from the language. [change_end] Most declarations are not used by the Common Lisp interpreter; they may be used to give advice to the compiler. The compiler may attempt to check your advice and warn you if it is inconsistent. Unlike most other Lisp dialects, Common Lisp recognizes special declarations in interpreted code as well as compiled code. This potential source of incompatibility between interpreted and compiled code is thereby eliminated in Common Lisp. The internal workings of a compiler will of course be highly implementation-dependent. The following functions provide a standard interface to the compiler, however. [old_change_begin] [Function] compile name &optional definition If definition is supplied, it should be a lambda-expression, the interpreted function to be compiled. If it is not supplied, then name should be a symbol with a definition that is a lambda-expression; that definition is compiled and the resulting compiled code is put back into the symbol as its function definition. [old_change_end] [change_begin] X3J13 voted in October 1988 (COMPILE-ARGUMENT-PROBLEMS) to restate the preceding paragraph more precisely and to extend the capabilities of compile. If the optional definition argument is supplied, it may be either a lambda-expression (which is coerced to a function) or a function to be compiled; if no definition is supplied, the symbol-function of the symbol is extracted and compiled. It is permissible for the symbol to have a macro definition rather than a function definition; both macros and functions may be compiled. It is an error if the function to be compiled was defined interpretively in a non-null lexical environment. (An implementation is free to extend the behavior of compile to compile such functions properly, but portable programs may not depend on this capability.) The consequences of calling compile on a function that is already compiled are unspecified. [change_end] [old_change_begin] The definition is compiled and a compiled-function object produced. If name is a non-nil symbol, then the compiled-function object is installed as the global function definition of the symbol and the symbol is returned. If name is nil, then the compiled-function object itself is returned. For example: (defun foo ...) => foo ØA function definition (compile 'foo) => foo ;Compile it ;Now foo runs faster (maybe) (compile nil '(lambda (a b c) (- (* b b) (* 4 a c)))) => a compiled function of three arguments that computes [old_change_end] [change_begin] X3J13 voted in June 1989 (COMPILER-DIAGNOSTICS) to specify that compile returns two additional values indicating whether the compiler issued any diagnostics (see section 25.1.1). X3J13 voted in March 1989 (FUNCTION-NAME) to extend compile to accept as a name any function-name (a symbol or a list whose car is setf-see section 7.1). One may write (compile '(setf cadr)) to compile the setf expansion function for cadr. [change_end] [old_change_begin] [Function] compile-file input-pathname &key :output-file The input-pathname must be a valid file specifier, such as a pathname. The defaults for input-filename are taken from the variable *default-pathname-defaults*. The file should be a Lisp source file; its contents are compiled and written as a binary object file. [old_change_end] [change_begin] X3J13 voted in March 1989 (COMPILER-VERBOSITY) to add two new keyword arguments :verbose and :print to compile-file by analogy with load. The new function definition is as follows. [Function] compile-file input-pathname &key :output-file :verbose :print The :verbose argument (which defaults to the value of *compile-verbose*), if true, permits compile-file to print a message in the form of a comment to *standard-output* indicating what file is being compiled and other useful information. The :print argument (which defaults to the value of *compile-print*), if true, causes information about top-level forms in the file being compiled to be printed to *standard-output*. Exactly what is printed is implementation-dependent; nevertheless something will be printed. X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which streams may be used as pathnames (see section 23.1.6). X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that supplying a wild pathname as the input-pathname argument to compile-file has implementation-dependent consequences; compile-file might signal an error, for example, or might compile all files that match the wild pathname. X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require compile-file to accept logical pathnames (see section 23.1.5). [change_end] The :output-file argument may be used to specify an output pathname; it defaults in a manner appropriate to the implementation's file system conventions. [change_begin] X3J13 voted in June 1989 (COMPILER-DIAGNOSTICS) to specify that compile-file returns three values: the truename of the output file (or nil if the file could not be created) and two values indicating whether the compiler issued any diagnostics (see section 25.1.1). X3J13 voted in October 1988 (COMPILE-FILE-PACKAGE) to specify that compile-file, like load, rebinds *package* to its current value. If some form in the file changes the value of *package*, the old value will be restored when compilation is completed. X3J13 voted in June 1989 (COMPILE-FILE-SYMBOL-HANDLING) to specify restrictions on conforming programs to ensure consistent handling of symbols and packages. In order to guarantee that compiled files can be loaded correctly, the user must ensure that the packages referenced in the file are defined consistently at compile and load time. Conforming Common Lisp programs must satisfy the following requirements. * The value of *package* when a top-level form in the file is processed by compile-file must be the same as the value of *package* when the code corresponding to that top-level form in the compiled file is executed by the loader. In particular, any top-level form in a file that alters the value of *package* must change it to a package of the same name at both compile and load time; moreover, if the first non-atomic top-level form in the file is not a call to in-package, then the value of *package* at the time load is called must be a package with the same name as the package that was the value of *package* at the time compile-file was called. * For every symbol appearing lexically within a top-level form that was accessible in the package that was the value of *package* during processing of that top-level form at compile time, but whose home package was another package, at load time there must be a symbol with the same name that is accessible in both the load-time *package* and in the package with the same name as the compile-time home package. * For every symbol in the compiled file that was an external symbol in its home package at compile time, there must be a symbol with the same name that is an external symbol in the package with the same name at load time. If any of these conditions do not hold, the package in which load looks for the affected symbols is unspecified. Implementations are permitted to signal an error or otherwise define this behavior. These requirements are merely an explicit statement of the status quo, namely that users cannot depend on any particular behavior if the package environment at load time is inconsistent with what existed at compile time. X3J13 voted in March 1989 (IN-SYNTAX) to specify that compile-file must bind *readtable* to its current value at the time compile-file is called; the dynamic extent of the binding should encompass all of the file-loading activity. This allows a portable program to include forms such as (in-package "FOO") (eval-when (:execute :load-toplevel :compile-toplevel) (setq *readtable* foo:my-readtable)) without performing a net global side effect on the loading environment. Such statements allow the remainder of such a file to be read either as interpreted code or by compile-file in a syntax determined by an alternative readtable. X3J13 voted in June 1989 (LOAD-TRUENAME) to require that compile-file bind two new variables *compile-file-pathname* and *compile-file-truename*; the dynamic extent of the bindings should encompass all of the file-compiling activity. [Variable] *compile-verbose* X3J13 voted in March 1989 (COMPILER-VERBOSITY) to add *compile-verbose*. This variable provides the default for the :verbose argument to compile-file. Its initial value is implementation-dependent. A proposal was submitted to X3J13 in October 1989 to rename this *compile-file-verbose* for consistency. [Variable] *compile-print* X3J13 voted in March 1989 (COMPILER-VERBOSITY) to add *compile-print*. This variable provides the default for the :print argument to compile-file. Its initial value is implementation-dependent. A proposal was submitted to X3J13 in October 1989 to rename this *compile-file-print* for consistency. [Variable] *compile-file-pathname* X3J13 voted in June 1989 (LOAD-TRUENAME) to introduce *compile-file-pathname*; it is initially nil but compile-file binds it to a pathname that represents the file name given as the first argument to compile-file merged with the defaults (see merge-pathname). [Variable] *compile-file-truename* X3J13 voted in June 1989 (LOAD-TRUENAME) to introduce *compile-file-truename*; it is initially nil but compile-file binds it to the ``true name'' of the pathname of the file being compiled. See truename. [Special Form] load-time-value form [read-only-p] X3J13 voted in March 1989 (LOAD-TIME-EVAL) to add a mechanism for delaying evaluation of a form until it can be done in the run-time environment. If a load-time-value expression is seen by compile-file, the compiler performs its normal semantic processing (such as macro expansion and translation into machine code) on the form, but arranges for the execution of the form to occur at load time in a null lexical environment, with the result of this evaluation then being treated as an immediate quantity (that is, as if originally quoted) at run time. It is guaranteed that the evaluation of the form will take place only once when the file is loaded, but the order of evaluation with respect to the execution of top-level forms in the file is unspecified. If a load-time-value expression appears within a function compiled with compile, the form is evaluated at compile time in a null lexical environment. The result of this compile-time evaluation is treated as an immediate quantity in the compiled code. In interpreted code, form is evaluated (by eval) in a null lexical environment and one value is returned. Implementations that implicitly compile (or partially compile) expressions passed to eval may evaluate the form only once, at the time this compilation is performed. This is intentionally similar to the freedom that implementations are given for the time of expanding macros in interpreted code. If the same (as determined by eq) list (load-time-value form) is evaluated or compiled more than once, it is unspecified whether the form is evaluated only once or is evaluated more than once. This can happen both when an expression being evaluated or compiled shares substructure and when the same expression is passed to eval or to compile multiple times. Since a load-time-value expression may be referenced in more than one place and may be evaluated multiple times by the interpreter, it is unspecified whether each execution returns a ``fresh'' object or returns the same object as some other execution. Users must use caution when destructively modifying the resulting object. If two lists (load-time-value form) are equal but not eq, their values always come from distinct evaluations of form. Coalescing of these forms is not permitted. The optional read-only-p argument designates whether the result may be considered a read-only constant. If nil (the default), the result must be considered ordinary, modifiable data. If t, the result is a read-only quantity that may, as appropriate, be copied into read-only space and may, as appropriate, be shared with other programs. The read-only-p argument is not evaluated and only the literal symbols t and nil are permitted. This new feature addresses the same set of needs as the now-defunct #, reader syntax but in a cleaner and more general manner. Note that #, syntax was reliably useful only inside quoted structure (though this was not explicitly mentioned in the first edition), whereas a load-time-value form must appear outside quoted structure in a for-evaluation position. See make-load-form. [change_end] [Function] disassemble name-or-compiled-function The argument should be a function object, a lambda-expression, or a symbol with a function definition. If the relevant function is not a compiled function, it is first compiled. In any case, the compiled code is then ``reverse-assembled'' and printed out in a symbolic format. This is primarily useful for debugging the compiler, but also often of use to the novice who wishes to understand the workings of compiled code. ------------------------------------------------------------------------------- Implementation note: Implementors are encouraged to make the output readable, preferably with helpful comments. ------------------------------------------------------------------------------- [change_begin] X3J13 voted in March 1988 (DISASSEMBLE-SIDE-EFFECT) to clarify that when disassemble compiles a function, it never installs the resulting compiled-function object in the symbol-function of a symbol. X3J13 voted in March 1989 (FUNCTION-NAME) to extend disassemble to accept as a name any function-name (a symbol or a list whose car is setf - see section 7.1). Thus one may write (disassemble '(setf cadr)) to disassemble the setf expansion function for cadr. [Function] function-lambda-expression fn X3J13 voted in January 1989 (FUNCTION-DEFINITION) to add a new function to allow the source code for a defined function to be recovered. (The committee noted that the first edition provided no portable way to recover a lambda-expression once it had been compiled or evaluated to produce a function.) This function takes one argument, which must be a function, and returns three values. The first value is the defining lambda-expression for the function, or nil if that information is not available. The lambda-expression may have been preprocessed in some ways but should nevertheless be of a form suitable as an argument to the function compile or for use in the function special form. The second value is nil if the function was definitely produced by closing a lambda-expression in the null lexical environment; it is some non-nil value if the function might have been closed in some non-null lexical environment. The third value is the ``name'' of the function; this is nil if the name is not available or if the function had no name. The name is intended for debugging purposes only and may be any Lisp object (not necessarily one that would be valid for use as a name in a defun or function special form, for example). ------------------------------------------------------------------------------- Implementation note: An implementation is always free to return the values nil, t, nil from this function but is encouraged to make more useful information available as appropriate. For example, it may not be desirable for files of compiled code to retain the source lambda-expressions for use after the file is loaded, but it is probably desirable for functions produced by ``in-core'' calls to eval, compile, or defun to retain the defining lambda-expression for debugging purposes. The function function-lambda-expression makes this information, if retained, accessible in a standard and portable manner. ------------------------------------------------------------------------------- [Macro] with-compilation-unit ({option-name option-value}*) {form}* X3J13 voted in March 1989 (WITH-COMPILATION-UNIT) to add with-compilation-unit, which executes the body forms as an implicit progn. Within the dynamic context of this form, warnings deferred by the compiler until ``the end of compilation'' will be deferred until the end of the outermost call to with-compilation-unit. The results are the same as those of the last of the forms (or nil if there is no form). Each option-name is an unevaluated keyword; each option-value is evaluated. The set of keywords permitted may be extended by the implementation, but the only standard option keyword is :override; the default value for this option is nil. If with-compilation-unit forms are nested dynamically, only the outermost such call has any effect unless the :override value of an inner call is true. The function compile-file should provide the effect of (with-compilation-unit (:override nil) ...) around its code. Any implementation-dependent extensions to this behavior may be provided only as the result of an explicit programmer request by use of an implementation-dependent keyword. It is forbidden for an implementation to attach additional meaning to a conforming use of this macro. Note that not all compiler warnings are deferred. In some implementations, it may be that none are deferred. This macro only creates an interface to the capability where it exists, it does not require the creation of the capability. An implementation that does not defer any compiler warnings may correctly implement this macro as an expansion into a simple progn. [change_end] ------------------------------------------------------------------------------- * Compiler Diagnostics * Compiled Functions * Compilation Environment * Similarity of Constants ------------------------------------------------------------------------------- 25.1.1. Compiler Diagnostics [change_begin] X3J13 voted in June 1987 (COMPILER-WARNING-STREAM) to specify that compile and compile-file may output warning messages; any such messages should go to the stream that is the value of *error-output*. X3J13 voted in June 1989 (COMPILER-DIAGNOSTICS) to specify the use of conditions to signal various erroneous situations during compilation. First, note that error and warning conditions may be signaled either by the compiler itself or by code being processed by the compiler (for example, arbitrary errors may occur during compile-time macro expansion or processing of eval-when forms). Considering only those conditions signaled by the compiler (as opposed to during compilation): * Conditions of type error may be signaled by the compiler in situations where the compilation cannot proceed without intervention. Examples of such situations may include errors when opening a file or syntax errors. * Conditions of type warning may be signaled by the compiler in situations where the standard explicitly states that a warning must, should, or may be signaled. They may also be signaled when the compiler can determine that a situation would result at runtime that would have undefined consequences or would cause an error to be signaled. Examples of such situations may include violations of type declarations, altering or rebinding a constant defined with defconstant, calls to built-in Lisp functions with too few or too many arguments or with malformed keyword argument lists, referring to a variable declared ignore, or unrecognized declaration specifiers. * The compiler is permitted to signal diagnostics about matters of programming style as conditions of type style-warning, a subtype of warning. Although a style-warning condition may be signaled in these situations, no implementation is required to do so. However, if an implementation does choose to signal a condition, that condition will be of type style-warning and will be signaled by a call to the function warn. Examples of such situations may include redefinition of a function with an incompatible argument list, calls to functions (other than built-in functions) with too few or too many arguments or with malformed keyword argument lists, unreferenced local variables not declared ignore, or standard declaration specifiers that are ignored by the particular compiler in question. Both compile and compile-file are permitted (but not required) to establish a handler for conditions of type error. Such a handler might, for example, issue a warning and restart compilation from some implementation-dependent point in order to let the compilation proceed without manual intervention. The functions compile and compile-file each return three values. See the definitions of these functions for descriptions of the first value. The second value is nil if no compiler diagnostics were issued, and true otherwise. The third value is nil if no compiler diagnostics other than style warnings were issued; a non-nil value indicates that there were ``serious'' compiler diagnostics issued or that other conditions of type error or warning (but not style-warning) were signaled during compilation. [change_end] ------------------------------------------------------------------------------- 25.1.2. Compiled Functions [change_begin] X3J13 voted in June 1989 (COMPILED-FUNCTION-REQUIREMENTS) to impose certain requirements on the functions produced by the compilation process. If a function is of type compiled-function, then all macro calls appearing lexically within the function have already been expanded and will not be expanded again when the function is called. The process of compilation effectively turns every macrolet or symbol-macrolet construct into a progn (or a locally) with all instances of the local macros in the body fully expanded. If a function is of type compiled-function, then all load-time-value forms appearing lexically within the function have already been pre-evaluated and will not be evaluated again when the function is called. Implementations are free to classify every function as a compiled-function provided that all functions satisfy the preceding requirements. Conversely, it is permissible for a function that is not a compiled-function to satisfy the preceding requirements. If one or more functions are defined in a file that is compiled with compile-file and the compiled file is subsequently loaded by the function load, the resulting loaded function definitions must be of type compiled-function. The function compile must produce an object of type compiled-function as the value that is either returned or stored into the symbol-function of a symbol argument. Note that none of these restrictions addresses questions of the compilation technology or target instruction set. For example, a compiled function does not necessarily consist of native machine instructions. These requirements merely specify the behavior of the type system with respect to certain actions taken by compile, compile-file, and load. [change_end] ------------------------------------------------------------------------------- 25.1.3. Compilation Environment [change_begin] X3J13 voted in June 1989 (COMPILE-ENVIRONMENT-CONSISTENCY) to specify what information must be available at compile time for correct compilation and what need not be available until run time. The following information must be present in the compile-time environment for a program to be compiled correctly. This information need not also be present in the run-time environment. * In conforming code, macros referenced in the code being compiled must have been previously defined in the compile-time environment. The compiler must treat as a function call any form that is a list whose car is a symbol that does not name a macro or special form. (This implies that setf methods must also be available at compile time.) * In conforming code, proclamations for special variables must be made in the compile-time environment before any bindings of those variables are processed by the compiler. The compiler must treat any binding of an undeclared variable as a lexical binding. The compiler may incorporate the following kinds of information into the code it produces, if the information is present in the compile-time environment and is referenced within the code being compiled; however, the compiler is not required to do so. When compile-time and run-time definitions differ, it is unspecified which will prevail within the compiled code (unless some other behavior is explicitly specified below). It is also permissible for an implementation to signal an error at run time on detecting such a discrepancy. In all cases, the absence of the information at compile time is not an error, but its presence may enable the compiler to generate more efficient code. * The compiler may assume that functions that are defined and declared inline in the compile-time environment will retain the same definitions at run time. * The compiler may assume that, within a named function, a recursive call to a function of the same name refers to the same function, unless that function has been declared notinline. (This permits tail-recursive calls of a function to itself to be compiled as jumps, for example, thereby turning certain recursive schemas into efficient loops.) * In the absence of notinline declarations to the contrary, compile-file may assume that a call within the file being compiled to a named function that is defined in that file refers to that function. (This rule permits block compilation of files.) The behavior of the program is unspecified if functions are redefined individually at run time. * The compiler may assume that the signature (or ``interface contract'') of all built-in Common Lisp functions will not change. In addition, the compiler may treat all built-in Common Lisp functions as if they had been proclaimed inline. * The compiler may assume that the signature (or ``interface contract'') of functions with ftype information available will not change. * The compiler may ``wire in'' (that is, open-code or inline) the values of symbolic constants that have been defined with defconstant in the compile-time environment. * The compiler may assume that any type definition made with defstruct or deftype in the compile-time environment will retain the same definition in the run-time environment. It may also assume that a class defined by defclass in the compile-time environment will be defined in the run-time environment in such a way as to have the same superclasses and metaclass. This implies that subtype/supertype relationships of type specifiers will not change between compile time and run time. (Note that it is not an error for an unknown type to appear in a declaration at compile time, although it is reasonable for the compiler to emit a warning in such a case.) * The compiler may assume that if type declarations are present in the compile-time environment, the corresponding variables and functions present in the run-time environment will actually be of those types. If this assumption is violated, the run-time behavior of the program is undefined. The compiler must not make any additional assumptions about consistency between the compile-time and run-time environments. In particular, the compiler may not assume that functions that are defined in the compile-time environment will retain either the same definition or the same signature at run time, except as described above. Similarly, the compiler may not signal an error if it sees a call to a function that is not defined at compile time, since that function may be provided at run time. X3J13 voted in January 1989 (COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS) to specify the compile-time side effects of processing various macro forms. Calls to defining macros such as defmacro or defvar appearing within a file being processed by compile-file normally have compile-time side effects that affect how subsequent forms in the same file are compiled. A convenient model for explaining how these side effects happen is that each defining macro expands into one or more eval-when forms and that compile-time side effects are caused by calls occurring in the body of an (eval-when (:compile-toplevel) ...) form. The affected defining macros and their specific side effects are as follows. In each case, it is identified what a user must do to ensure that a program is conforming, and what a compiler must do in order to correctly process a conforming program. deftype The user must ensure that the body of a deftype form is evaluable at compile time if the type is referenced in subsequent type declarations. The compiler must ensure that a type specifier defined by deftype is recognized in subsequent type declarations. If the expansion of a type specifier is not defined fully at compile time (perhaps because it expands into an unknown type specifier or a satisfies of a named function that isn't defined in the compile-time environment), an implementation may ignore any references to this type in declarations and may signal a warning. defmacro and define-modify-macro The compiler must store macro definitions at compile time, so that occurrences of the macro later on in the file can be expanded correctly. The user must ensure that the body of the macro is evaluable at compile time if it is referenced within the file being compiled. defun No required compile-time side effects are associated with defun forms. In particular, defun does not make the function definition available at compile time. An implementation may choose to store information about the function for the purposes of compile-time error checking (such as checking the number of arguments on calls) or to permit later inline expansion of the function. defvar and defparameter The compiler must recognize that the variables named by these forms have been proclaimed special. However, it must not evaluate the initial-value form or set the variable at compile time. defconstant The compiler must recognize that the symbol names a constant. An implementation may choose to evaluate the value-form at compile time, load time, or both. Therefore the user must ensure that the value-form is evaluable at compile time (regardless of whether or not references to the constant appear in the file) and that it always evaluates to the same value. (There has been considerable variance among implementations on this point. The effect of this specification is to legitimize all of the implementation variants by requiring care of the user.) defsetf and define-setf-method The compiler must make setf methods available so that they may be used to expand calls to setf later on in the file. Users must ensure that the body of a call to define-setf-method or the complex form of defsetf is evaluable at compile time if the corresponding place is referred to in a subsequent setf in the same file. The compiler must make these setf methods available to compile-time calls to get-setf-method when its environment argument is a value received as the &environment parameter of a macro. defstruct The compiler must make the structure type name recognized as a valid type name in subsequent declarations (as described above for deftype) and make the structure slot accessors known to setf. In addition, the compiler must save enough information so that further defstruct definitions can include (with the :include option) a structure type defined earlier in the file being compiled. The functions that defstruct generates are not defined in the compile-time environment, although the compiler may save enough information about the functions to allow inline expansion of subsequent calls to these functions. The #S reader syntax may or may not be available for that structure type at compile time. define-condition The rules are essentially the same as those for defstruct. The compiler must make the condition type recognizable as a valid type name, and it must be possible to reference the condition type as the parent-type of another condition type in a subsequent define-condition form in the file being compiled. defpackage All of the actions normally performed by the defpackage macro at load time must also be performed at compile time. Compile-time side effects may cause information about a definition to be stored in a different manner from information about definitions processed either interpretively or by loading a compiled file. In particular, the information stored by a defining macro at compile time may or may not be available to the interpreter (either during or after compilation) or during subsequent calls to compile or compile-file. For example, the following code is not portable because it assumes that the compiler stores the macro definition of foo where it is available to the interpreter. (defmacro foo (x) `(car ,x)) (eval-when (:execute :compile-toplevel :load-toplevel) (print (foo '(a b c)))) ;Wrong The goal may be accomplished portably by including the macro definition within the eval-when form: (eval-when (eval compile load) (defmacro foo (x) `(car ,x)) (print (foo '(a b c)))) ;Right declaim X3J13 voted in June 1989 (PROCLAIM-ETC-IN-COMPILE-FILE) to add a new macro declaim for making proclamations recognizable at compile time. The declaration specifiers in the declaim form are effectively proclaimed at compile time so as to affect compilation of subsequent forms. (Note that compiler processing of a call to proclaim does not have any compile-time side effects, for proclaim is a function.) in-package X3J13 voted in March 1989 (IN-PACKAGE-FUNCTIONALITY) to specify that all of the actions normally performed by the in-package macro at load time must also be performed at compile time. X3J13 voted in June 1989 (CLOS-MACRO-COMPILATION) to specify the compile-time side effects of processing various CLOS-related macro forms. Top-level calls to the CLOS defining macros have the following compile-time side effects; any other compile-time behavior is explicitly left unspecified. defclass The class name may appear in subsequent type declarations and can be used as a specializer in subsequent defmethod forms. Thus the compile-time behavior of defclass is similar to that of deftype or defstruct. defgeneric The generic function can be referenced in subsequent defmethod forms, but the compiler does not arrange for the generic function to be callable at compile time. defmethod The compiler does not arrange for the method to be callable at compile time. If there is a generic function with the same name defined at compile time, compiling a defmethod form does not add the method to that generic function; the method is added to the generic function only when the defmethod form is actually executed. The error-signaling behavior described in the specification of defmethod in chapter 28 (if the function isn't a generic function or if the lambda-list is not congruent) occurs only when the defining form is executed, not at compile time. The forms in eql parameter specializers are evaluated when the defmethod form is executed. The compiler is permitted to build in knowledge about what the form in an eql specializer will evaluate to in cases where the ultimate result can be syntactically inferred without actually evaluating it. define-method-combination The method combination can be used in subsequent defgeneric forms. The body of a define-method-combination form is evaluated no earlier than when the defining macro is executed and possibly as late as generic function invocation time. The compiler may attempt to evaluate these forms at compile time but must not depend on being able to do so. [change_end] ------------------------------------------------------------------------------- 25.1.4. Similarity of Constants [change_begin] X3J13 voted in March 1989 (CONSTANT-COMPILABLE-TYPES) to specify what objects can be in compiled constants and what relationship there must be between a constant passed to the compiler and the one that is established by compiling it and then loading its file. The key is a definition of an equivalence relationship called ``similarity as constants'' between Lisp objects. Code passed through the file compiler and then loaded must behave as though quoted constants in it are similar in this sense to quoted constants in the corresponding source code. An object may be used as a quoted constant processed by compile-file if and only if the compiler can guarantee that the resulting constant established by loading the compiled file is ``similar as a constant'' to the original. Specific requirements are spelled out below. Some types of objects, such as streams, are not supported in constants processed by the file compiler. Such objects may not portably appear as constants in code processed with compile-file. Conforming implementations are required to handle such objects either by having the compiler or loader reconstruct an equivalent copy of the object in some implementation-specific manner or by having the compiler signal an error. Of the types supported in constants, some are treated as aggregate objects. For these types, being similar as constants is defined recursively. We say that an object of such a type has certain ``basic attributes''; to be similar as a constant to another object, the values of the corresponding attributes of the two objects must also be similar as constants. A definition of this recursive form has problems with any circular or infinitely recursive object such as a list that is an element of itself. We use the idea of depth-limited comparison and say that two objects are similar as constants if they are similar at all finite levels. This idea is implicit in the definitions below, and it applies in all the places where attributes of two objects are required to be similar as constants. The question of handling circular constants is the subject of a separate vote by X3J13 (see below). The following terms are used throughout this section. The term constant refers to a quoted or self-evaluating constant, not a named constant defined by defconstant. The term source code is used to refer to the objects constructed when compile-file calls read (or the equivalent) and to additional objects constructed by macro expansion during file compilation. The term compiled code is used to refer to objects constructed by load. Two objects are similar as a constant if and only if they are both of one of the types listed below and satisfy the additional requirements listed for that type. number Two numbers are similar as constants if they are of the same type and represent the same mathematical value. character Two characters are similar as constants if they both represent the same character. (The intent is that this be compatible with how eql is defined on characters.) symbol X3J13 voted in June 1989 (COMPILE-FILE-SYMBOL-HANDLING) to define similarity as a constant for interned symbols. A symbol S appearing in the source code is similar as a constant to a symbol S' in the compiled code if their print names are similar as constants and either of the following conditions holds: o S is accessible in *package* at compile time and S' is accessible in *package* at load time. o S' is accessible in the package that is similar as a constant to the home package of symbol S. The ``similar as constants'' relationship for interned symbols has nothing to do with *readtable* or how the function read would parse the characters in the print name of the symbol. An uninterned symbol in the source code is similar as a constant to an uninterned symbol in the compiled code if their print names are similar as constants. package A package in the source code is similar as a constant to a package in the compiled code if their names are similar as constants. Note that the loader finds the corresponding package object as if by calling find-package with the package name as an argument. An error is signaled if no package of that name exists at load time. random-state We say that two random-state objects are functionally equivalent if applying random to them repeatedly always produces the same pseudo-random numbers in the same order. Two random-states are similar as constants if and only if copies of them made via make-random-state are functionally equivalent. (Note that a constant random-state object cannot be used as the state argument to the function random because random performs a side effect on that argument.) cons Two conses are similar as constants if the values of their respective car and cdr attributes are similar as constants. array Two arrays are similar as constants if the corresponding values of each of the following attributes are similar as constants: for vectors (one-dimensional arrays), the length and element-type and the result of elt for all valid indices; for all other arrays, the array-rank, the result of array-dimension for all valid axis numbers, the array-element-type, and the result of aref for all valid indices. (The point of distinguishing vectors is to take any fill pointers into account.) If the array in the source code is a simple-array, then the corresponding array in the compiled code must also be a simple-array, but if the array in the source code is displaced, has a fill pointer, or is adjustable, the corresponding array in the compiled code is permitted to lack any or all of these qualities. hash-table Two hash tables are similar as constants if they meet three requirements. First, they must have the same test (for example, both are eql hash tables or both are equal hash tables). Second, there must be a unique bijective correspondence between the keys of the two tables, such that the corresponding keys are similar as constants. Third, for all keys, the values associated with two corresponding keys must be similar as constants. If there is more than one possible one-to-one correspondence between the keys of the two tables, it is unspecified whether the two tables are similar as constants. A conforming program cannot use such a table as a constant. pathname Two pathnames are similar as constants if all corresponding pathname components are similar as constants. stream, readtable, and method Objects of these types are not supported in compiled constants. function X3J13 voted in June 1989 (CONSTANT-FUNCTION-COMPILATION) to specify that objects of type function are not supported in compiled constants. structure and standard-object X3J13 voted in March 1989 (LOAD-OBJECTS) to introduce a facility based on the Common Lisp Object System whereby a user can specify how compile-file and load must cooperate to reconstruct compile-time constant objects at load time (see make-load-form). X3J13 voted in March 1989 (CONSTANT-COLLAPSING) to specify the circumstances under which constants may be coalesced in compiled code. Suppose A and B are two objects used as quoted constants in the source code, and that A' and B' are the corresponding objects in the compiled code. If A' and B' are eql but A and B were not eql, then we say that A and B have been coalesced by the compiler. An implementation is permitted to coalesce constants appearing in code to be compiled if and only if they are similar as constants, except that objects of type symbol, package, structure, or standard-object obey their own rules and may not be coalesced by a separate mechanism. ------------------------------------------------------------------------------- Rationale: Objects of type symbol and package cannot be coalesced because the fact that they are named, interned objects means they are already as coalesced as it is useful for them to be. Uninterned symbols could perhaps be coalesced, but that was thought to be more dangerous than useful. Structures and objects could be coalesced if a ``similar as a constant'' predicate were defined for them; it would be a generic function. However, at present there is no such predicate. Currently make-load-form provides a protocol by which compile-file and load work together to construct an object in the compiled code that is equivalent to the object in the source code; a different mechanism would have to be added to permit coalescing. ------------------------------------------------------------------------------- Note that coalescing is possible only because it is forbidden to destructively modify constants (CONSTANT-MODIFICATION) (see quote). X3J13 voted in March 1989 (CONSTANT-CIRCULAR-COMPILATION) to specify that objects containing circular or infinitely recursive references may legitimately appear as constants to be compiled. The compiler is required to preserve eql-ness of substructures within a file compiled by compile-file. [change_end] ------------------------------------------------------------------------------- 25.2. Documentation [old_change_begin] A simple facility is provided for attaching strings to symbols for the purpose of on-line documentation. Rather than using the property list of the symbol, a separate function documentation is provided so that implementations can optimize the storage of documentation strings. [Function] documentation symbol doc-type This function returns the documentation string of type doc-type for the symbol, or nil if none exists. Both arguments must be symbols. Some kinds of documentation are provided automatically by certain Common Lisp constructs if the user writes an optional documentation string within them: Construct Documentation Type ============================================ defvar variable defparameter variable defconstant variable defun function defmacro function defstruct structure deftype type defsetf setf ============================================ In addition, names of special forms may also have function documentation. (Macros and special forms are not really functions, of course, but it is convenient to group them with functions for documentation purposes.) setf may be used with documentation to update documentation information. [old_change_end] [change_begin] X3J13 voted in June 1988 (CLOS) to make documentation a CLOS generic function (see chapter 28). X3J13 voted in March 1989 (FUNCTION-NAME) to extend documentation to accept any function-name (a symbol or a list whose car is setf - see section 7.1). Thus one may write (documentation '(setf cadr) 'function) to determine whether there is any documentation for a setf expansion function for cadr. [change_end] ------------------------------------------------------------------------------- 25.4. Environment Inquiries Environment inquiry functions provide information about the environment in which a Common Lisp program is being executed. They are described here in two categories: first, those dealing with determination and measurement of time, and second, all the others, most of which deal with identification of the computer hardware and software. ------------------------------------------------------------------------------- * Time Functions * Other Environment Inquiries ------------------------------------------------------------------------------- 25.4.1. Time Functions Time is represented in three different ways in Common Lisp: Decoded Time, Universal Time, and Internal Time. The first two representations are used primarily to represent calendar time and are precise only to one second. Internal Time is used primarily to represent measurements of computer time (such as run time) and is precise to some implementation-dependent fraction of a second, as specified by internal-time-units-per-second. Decoded Time format is used only for absolute time indications. Universal Time and Internal Time formats are used for both absolute and relative times. Decoded Time format represents calendar time as a number of components: * Second: an integer between 0 and 59, inclusive. * Minute: an integer between 0 and 59, inclusive. * Hour: an integer between 0 and 23, inclusive. * Date: an integer between 1 and 31, inclusive (the upper limit actually depends on the month and year, of course). * Month: an integer between 1 and 12, inclusive; 1 means January, 12 means December. * Year: an integer indicating the year A.D. However, if this integer is between 0 and 99, the ``obvious'' year is used; more precisely, that year is assumed that is equal to the integer modulo 100 and within fifty years of the current year (inclusive backwards and exclusive forwards). Thus, in the year 1978, year 28 is 1928 but year 27 is 2027. (Functions that return time in this format always return a full year number.) ------------------------------------------------------------------------------- Compatibility note: This is incompatible with the Lisp Machine Lisp definition in two ways. First, in Lisp Machine Lisp a year between 0 and 99 always has 1900 added to it. Second, in Lisp Machine Lisp time functions return the abbreviated year number between 0 and 99 rather than the full year number. The incompatibility is prompted by the imminent arrival of the twenty-first century. Note that (mod year 100) always reliably converts a year number to the abbreviated form, while the inverse conversion can be very difficult. ------------------------------------------------------------------------------- * Day-of-week: an integer between 0 and 6, inclusive; 0 means Monday, 1 means Tuesday, and so on; 6 means Sunday. * Daylight-saving-time-p: a flag that, if not nil, indicates that daylight saving time is in effect. * Time-zone: an integer specified as the number of hours west of GMT (Greenwich Mean Time). For example, in Massachusetts the time zone is 5, and in California it is 8. Any adjustment for daylight saving time is separate from this. [change_begin] X3J13 voted in March 1989 (TIME-ZONE-NON-INTEGER) to specify that the time zone part of Decoded Time need not be an integer, but may be any rational number (either an integer or a ratio) in the range -24 to 24 (inclusive on both ends) that is an integral multiple of 1/3600. ------------------------------------------------------------------------------- Rationale: For all possible time designations to be accommodated, it is necessary to allow the time zone to be non-integral, for some places in the world have time standards offset from Greenwich Mean Time by a non-integral number of hours. There appears to be no user demand for floating-point time zones. Since such zones would introduce inexact arithmetic, X3J13 did not consider adding them at this time. This specification does require time zones to be represented as integral multiples of 1 second (rather than 1 hour). This prevents problems that could otherwise occur in converting Decoded Time to Universal Time. ------------------------------------------------------------------------------- [change_end] Universal Time represents time as a single non-negative integer. For relative time purposes, this is a number of seconds. For absolute time, this is the number of seconds since midnight, January 1, 1900 GMT. Thus the time 1 is 00:00:01 (that is, 12:00:01 A.M.) on January 1, 1900 GMT. Similarly, the time 2398291201 corresponds to time 00:00:01 on January 1, 1976 GMT. Recall that the year 1900 was not a leap year; for the purposes of Common Lisp, a year is a leap year if and only if its number is divisible by 4, except that years divisible by 100 are not leap years, except that years divisible by 400 are leap years. Therefore the year 2000 will be a leap year. (Note that the ``leap seconds'' that are sporadically inserted by the world's official timekeepers as an additional correction are ignored; Common Lisp assumes that every day is exactly 86400 seconds long.) Universal Time format is used as a standard time representation within the ARPANET; see reference [22]. Because the Common Lisp Universal Time representation uses only non-negative integers, times before the base time of midnight, January 1, 1900 GMT cannot be processed by Common Lisp. Internal Time also represents time as a single integer, but in terms of an implementation-dependent unit. Relative time is measured as a number of these units. Absolute time is relative to an arbitrary time base, typically the time at which the system began running. [Function] get-decoded-time The current time is returned in Decoded Time format. Nine values are returned: second, minute, hour, date, month, year, day-of-week, daylight-saving-time-p, and time-zone. ------------------------------------------------------------------------------- Compatibility note: In Lisp Machine Lisp time-zone is not currently returned. Consider, however, the use of Common Lisp in some mobile vehicle. It is entirely plausible that the time zone might change from time to time. ------------------------------------------------------------------------------- [Function] get-universal-time The current time of day is returned as a single integer in Universal Time format. [Function] decode-universal-time universal-time &optional time-zone The time specified by universal-time in Universal Time format is converted to Decoded Time format. Nine values are returned: second, minute, hour, date, month, year, day-of-week, daylight-saving-time-p, and time-zone. ------------------------------------------------------------------------------- Compatibility note: In Lisp Machine Lisp time-zone is not currently returned. Consider, however, the use of Common Lisp in some mobile vehicle. It is entirely plausible that the time zone might change from time to time. ------------------------------------------------------------------------------- The time-zone argument defaults to the current time zone. [change_begin] X3J13 voted in January 1989 (DECODE-UNIVERSAL-TIME-DAYLIGHT) to specify that decode-universal-time, like encode-universal-time, ignores daylight saving time information if a time-zone is explicitly specified; in this case the returned daylight-saving-time-p value will necessarily be nil even if daylight saving time happens to be in effect in that time zone at the specified time. [change_end] [Function] encode-universal-time second minute hour date month year &optional time-zone The time specified by the given components of Decoded Time format is encoded into Universal Time format and returned. If you do not specify time-zone, it defaults to the current time zone adjusted for daylight saving time. If you provide time-zone explicitly, no adjustment for daylight saving time is performed. [Constant] internal-time-units-per-second This value is an integer, the implementation-dependent number of internal time units in a second. (The internal time unit must be chosen so that one second is an integral multiple of it.) ------------------------------------------------------------------------------- Rationale: The reason for allowing the internal time units to be implementation-dependent is so that get-internal-run-time and get-internal-real-time can execute with minimum overhead. The idea is that it should be very likely that a fixnum will suffice as the returned value from these functions. This probability can be tuned to the implementation by trading off the speed of the machine against the word size. Any particular unit will be inappropriate for some implementations: a microsecond is too long for a very fast machine, while a much smaller unit would force many implementations to return bignums for most calls to get-internal-time, rendering that function less useful for accurate timing measurements. ------------------------------------------------------------------------------- [Function] get-internal-run-time The current run time is returned as a single integer in Internal Time format. The precise meaning of this quantity is implementation-dependent; it may measure real time, run time, CPU cycles, or some other quantity. The intent is that the difference between the values of two calls to this function be the amount of time between the two calls during which computational effort was expended on behalf of the executing program. [Function] get-internal-real-time The current time is returned as a single integer in Internal Time format. This time is relative to an arbitrary time base, but the difference between the values of two calls to this function will be the amount of elapsed real time between the two calls, measured in the units defined by internal-time-units-per-second. [Function] sleep seconds (sleep n) causes execution to cease and become dormant for approximately n seconds of real time, whereupon execution is resumed. The argument may be any non-negative non-complex number. sleep returns nil. ------------------------------------------------------------------------------- 25.4.2. Other Environment Inquiries For any of the following functions, if no appropriate and relevant result can be produced, nil is returned instead of a string. ------------------------------------------------------------------------------- Rationale: These inquiry facilities are functions rather than variables against the possibility that a Common Lisp process might migrate from machine to machine. This need not happen in a distributed environment; consider, for example, dumping a core image file containing a compiler and then shipping it to another site. ------------------------------------------------------------------------------- [Function] lisp-implementation-type A string is returned that identifies the generic name of the particular Common Lisp implementation. Examples: "Spice LISP", "Zetalisp". [Function] lisp-implementation-version A string is returned that identifies the version of the particular Common Lisp implementation; this information should be of use to maintainers of the implementation. Examples: "1192", "53.7 with complex numbers", "1746.9A, NEWIO 53, ETHER 5.3". [Function] machine-type A string is returned that identifies the generic name of the computer hardware on which Common Lisp is running. Examples: "IMLAC", "DEC PDP-10", "DEC VAX-11/780". [Function] machine-version A string is returned that identifies the version of the computer hardware on which Common Lisp is running. Example: "KL10, microcode 9". [Function] machine-instance A string is returned that identifies the particular instance of the computer hardware on which Common Lisp is running; this might be a local nickname, for example, or a serial number. Examples: "MIT-MC", "CMU GP-VAX". [Function] software-type A string is returned that identifies the generic name of any relevant supporting software. Examples: "Spice", "TOPS-20", "ITS". [Function] software-version A string is returned that identifies the version of any relevant supporting software; this information should be of use to maintainers of the implementation. [Function] short-site-name long-site-name A string is returned that identifies the physical location of the computer hardware. Examples of short names: "MIT AI Lab", "CMU-CSD". Examples of long names: "MIT Artificial Intelligence Laboratory" "Massachusetts Institute of Technology Artificial Intelligence Laboratory" "Carnegie-Mellon University Computer Science Department" See also user-homedir-pathname. [Variable] *features* The value of the variable *features* should be a list of symbols that name ``features'' provided by the implementation. Most such names will be implementation-specific; typically a name for the implementation will be included. [old_change_begin] One standard feature name is ieee-floating-point, which should be present if and only if full IEEE proposed floating-point arithmetic [23] is supported. [old_change_end] The value of this variable is used by the #+ and #- reader syntax. [change_begin] X3J13 voted in March 1988 (SHARPSIGN-PLUS-MINUS-PACKAGE) to specify that feature names used with #+ and #- are read in the keyword package unless an explicit prefix designating some other package appears. The standard feature name ieee-floating-point is therefore actually the keyword :ieee-floating-point, though one need not write the colon when using it with #+ or #-; thus #+ieee-floating-point and #+:ieee-floating-point mean the same thing. [change_end] ------------------------------------------------------------------------------- 25.5. Identity Function This function is occasionally useful as an argument to other functions that require functions as arguments. (Got that?) [Function] identity object The object is returned as the value of identity. [change_begin] The identity function is the default value for the :key argument to many sequence functions (see chapter 14). Table 12-1 illustrates the behavior in the complex plane of the identity function regarded as a function of a complex numerical argument. Many other constructs in Common Lisp have the behavior of identity when given a single argument. For example, one might well use values in place of identity. However, writing values of a single argument conventionally indicates that the argument form might deliver multiple values and that the intent is to pass on only the first of those values. ------------------------------------------------------------------------------- Compatibility note: In Maclisp, progn was a function of any number of arguments that returned its last argument, so progn could be used as an identity function. In Common Lisp, progn is a special form and therefore cannot be used for that purpose. ------------------------------------------------------------------------------- [change_end] -------------------------------------------------------------------------------